<!DOCTYPE HTML>
<html>
<head>
<title>The BOOMR API</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../boomerang-docs.css">
</head>
<body>
<span style="float:right;"><a href="../">All Docs</a> | <a href="index.html">Index</a></span>
<h1>The BOOMR object</h1>
<p>
Everything in boomerang is accessed through the <code>BOOMR</code> object.  Each plugin has its
own API, but is reachable through <code>BOOMR.plugins</code>.  This document describes the main
<code>BOOMR</code> object.
</p>

<p>
To access any of the following, dereference the BOOMR object.  eg: use <code>BOOMR.version</code> 
to get the <code>version</code> string.
</p>

<h2 id="properties">Properties</h2>

<dl class="api">

<dt>version</dt>
<dd>
<p>
The version number of the boomerang library.  This is a string, formatted as major.minor.patchlevel.
Standard version numbering rules apply
</p>
</dd>

<dt>plugins</dt>
<dd>
<p>
An object containing all plugins that have been added to boomerang.  If you build your own plugin,
it should be added to this object:
</p>
<pre>
BOOMR.plugins.MyPlugin = {
	...
};</pre>
</dd>

</dl>

<h2 id="methods">Methods</h2>

<dl class="api">

<dt>init(oConfig)</dt>
<dd>
<p>
The init method that you to call to initialise boomerang.  Call this method once after you've
loaded the boomerang javascript.  It accepts a single configuration object as a parameter.  The
configuration object is described in <a href="../howtos/howto-6.html">Howto #6 &mdash; Configuring boomerang</a>.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>page_ready()</dt>
<dd>
<p>
Method that fires the <code>page_ready</code> event.  Call this only if you've set <code>autorun</code> to
false when calling the <code>init()</code> method.  You should call this method when you determine that
your page is ready to be used by your user.  This will be the end-time used in the page load time measurement.
</p>
<h3>Example:</h3>
<p>
See <a href="../howtos/howto-1b-page%231.html">Howto #1b</a> for an example of how to use this method.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>subscribe(sEvent, fCallbackFn, oCallbackData, oCallbackScope)</dt>
<dd>
<p>
The subscribe method is used to subscribe an event handler to one of boomerang's <a href="#events">events</a>.
It accepts four parameters:
</p>
<h3>Parameters:</h3>
  <dl>
  <dt>sEvent</dt>
  <dd>The event name.  This may be one of <em>page_ready</em>, <em>page_unload</em>, <em>before_beacon</em></dd>

  <dt>fCallbackFn</dt>
  <dd>A reference to the callback function that will be called when this event fires.  The function's signature should be:
  <pre>function(oEventData, oCallbackData);</pre>
  </dd>

  <dt>oCallbackData</dt>
  <dd><strong>[optional]</strong> object passed as the second parameter to the callback function</dd>

  <dt>oCallbackScope</dt>
  <dd><strong>[optional]</strong> If set to an object, then the callback function is called as a method of this object, and all references to <code>this</code>
  within the callback function will refer to oCallbackScope</dd>
  </dl>
<p>
The <code>page_ready</code> and <code>page_unload</code> events are most useful to plugins while the
<code>before_beacon</code> event is useful to code that wants to do something with the beacon parameters
before the beacon is fired.  See the <a href="#events">events</a> section for more details.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>addVar(sName, sValue) OR addVar(oVars)</dt>
<dd>
<p>
Add one or more parameters to the beacon.  This method is used by plugins to add parameters to the beacon,
but may also be used by the page developer to tag the current request.
</p>
<h3>Example:</h3>
<p>
See <a href="../howtos/howto-5.html">Howto #5</a> for an example of using <code>addVar()</code>.
</p>
<p>
This method may either be called with a single object containing key/value pairs, or with two parameters,
the first is the variable name and the second is its value.  All names should be strings usable in a URL's
query string.  We recommend only using alphanumeric characters and underscores, but you can use anything you
like.  Values should be strings (or numbers), and have the same restrictions as names.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>removeVar(sName, ...)</dt>
<dd>
<p>
Removes one or more variables from the beacon URL.  This is useful within a plugin to reset the values of
parameters that it is about to set.  It can also be used in a <code>before_beacon</code> handler to stop
the beacon from being sent.  See <a href="../howtos/howto-5.html">Howto #5</a> for how to do this.
</p>
<p>
This method accepts either a list of variable names, or a single array containing a list of variable names.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>sendBeacon()</dt>
<dd>
<p>
Request boomerang to send its beacon.  Boomerang may ignore this request.  When this method is called,
boomerang checks all plugins.  If any plugin has not completed its checks (ie, the plugin's <code>is_complete()</code>
method returns false, then this method does nothing.  If all plugins have completed, then this method fires the
<code>before_beacon</code> event with all variables that will be sent on the beacon.
</p>
<p>
After all <code>before_beacon</code> handlers return, this method checks if a <code>beacon_url</code> has been
configured and if there are any beacon parameters to be sent.  If both are true, it fires the beacon.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>log(sMessage, sLevel, sSource)</dt>
<dd>
<p>
Log a <code>sMessage</code> to the configured logger with a level of <code>sLevel</code>.  This method
simply passes all logging information on to the configured logger.  See
<a href="../howtos/howto-6.html">Howto #6</a> for details on how to configure this.
</p>
<p>
You probably want to use one of the convenience methods below instead that set the log level correctly.
</p>
<h3>Returns</h3>
<p>
nothing
</p>
</dd>

<dt>debug(sMessage, sSource)</dt>
<dd>
<p>
Log <code>sMessage</code> to the configured logger with a level of <code>debug</code>.  If <code>sSource</code> is set,
it is appended to the string "boomerang." and set as the source of the log message.  Use this
parameter to mention a plugin name and/or a line number/function name.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>info(sMessage, sSource)</dt>
<dd>
<p>
Log <code>sMessage</code> to the configured logger with a level of <code>info</code>.  If <code>sSource</code> is set,
it is appended to the string "boomerang." and set as the source of the log message.  Use this
parameter to mention a plugin name and/or a line number/function name.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>warn(sMessage, sSource)</dt>
<dd>
<p>
Log <code>sMessage</code> to the configured logger with a level of <code>warn</code>.  If <code>sSource</code> is set,
it is appended to the string "boomerang." and set as the source of the log message.  Use this
parameter to mention a plugin name and/or a line number/function name.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>error(sMessage, sSource)</dt>
<dd>
<p>
Log <code>sMessage</code> to the configured logger with a level of <code>error</code>.  If <code>sSource</code> is set,
it is appended to the string "boomerang." and set as the source of the log message.  Use this
parameter to mention a plugin name and/or a line number/function name.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

</dl>

<h2 id="events">Events</h2>

<dl class="api">
<dt>page_ready</dt>
<dd>
<p>
Fired when the page is usable by the user.  By default this is fired when <code>window.onload</code> fires,
but if you set <code>autorun</code> to <code>false</code> when calling <code>BOOMR.init()</code>, then
you must explicitly fire this event by calling <code>BOOMR.page_ready()</code>.
</p>
<h3>Callback</h3>
<p>
No additional event data is passed to the callback function.  Any callback data is passed as specified in
the <code>subscribe()</code> method.
</p>
</dd>

<dt>page_unload</dt>
<dd>
<p>
Fired just before the browser unloads the page.  This is fired when <code>window.onbeforeunload</code> fires
(<code>onunload</code> on Opera).
</p>
<h3>Callback</h3>
<p>
No additional event data is passed to the callback function.  Any callback data is passed as specified in
the <code>subscribe()</code> method.
</p>
</dd>

<dt>before_beacon</dt>
<dd>
<p>
Fired just before the beacon is sent to the server.  You can stop the beacon from firing by calling
<code>BOOMR.removeVar()</code> for all beacon parameters.
</p>
<h3>Callback</h3>
<p>
The callback function is called with two parameters.  The first parameter is an object containing all
parameters that will be added to the beacon.  The second parameter is the callback data object that
was passed in to the <code>subscribe()</code> method.  If the callback function removes all parameters
from boomerang, the beacon will not fire.
</p>
</dd>

</dl>

<p>
The latest code and docs is available on <a href="http://github.com/yahoo/boomerang/">github.com/yahoo/boomerang</a>
</p>

</body>
</html>
